Paired: GitHub #476 ↔ GitCode !2291

加入 list_checkpoint 工具

What type of PR is this?

/kind feature

背景

F_76 持久化后，命名 checkpoint 仍存在三个可发现性问题：

1. 名字无固定渠道传递：checkpoint() 的结果只写进调用成员自己的上下文，leader 是否知道名字完全取决于成员自觉 send_message + leader 猜对字符串。
2. leader 无法查询：权威快照在 leader 内存 _named_checkpoints（F_76 后持久化于 session namespace），但没有任何团队工具把它暴露给 LLM。
3. 用错名字静默回退：fork="<wrong>" 找不到时只记日志 warning，然后静默回退为全量继承，leader 完全不知情。

方案

1. checkpoint 记录格式扩展（可查的前提）

快照从 name → message_count 升级为 name → {count, description, created_by}：

• runtime/metadata.py：read_team_checkpoints 兼容新记录与旧 int blob（兜底转空记录），脏值不炸冷恢复。
• agent/team_agent.py：set_checkpoint(name, count, *, description, created_by) 存成记录；fork 解析改为取 record["count"]（截断行为不变）。
• tools/team.py：store_checkpoint 组装记录、默认 created_by=member_name。
• spawn/inprocess_spawn.py：store 回调直传 leader set_checkpoint，description/created_by 自动透传。

2. list_checkpoints 工具（leader-only 查询）

• tools/tool_member.py：新增 ListCheckpointsTool，零参数，返回 [{name, message_count, description, created_by}]；map_result 逐行渲染，空集返回 "No checkpoints"。
• tools/team.py：set_checkpoint_list_fn / list_checkpoints()（优先回调取 leader 的 _named_checkpoints，否则兜底本地 dict）。
• agent/team_agent.py _setup_infra：leader 接线 set_checkpoint_list_fn(lambda: self._named_checkpoints)。
• tools/tool_factory.py 注册；tools/tool_permissions.py 加入 LEADER_ONLY_TOOLS（外部 member scope 按角色过滤、operator 控制面不经 create_team_tools，天然不可见）。
• 新增 tools/locales/descs/en|cn/list_checkpoints.md：描述含"fork 前必须调用核对名字"契约。

3. 成员打 checkpoint 自动通知 leader

• tools/tool_member.py CheckpointTool：保存后调 _notify_leader_created——非 leader 成员自动 send_message 给 leader，内容 [checkpoint] 'name' created by member at message N (description)。
• tools/locales/en.py / cn.py：新增 checkpoint.notify_leader 文案。

4. fork 名不匹配可见化

• agent/team_agent.py：新增 _notify_fork_name_not_found，命名 fork 找不到时 best-effort 给 leader 发消息，列出可用 checkpoint 清单；不阻断 spawn（仍回退全量）。
• i18n.py：新增 checkpoint.fork_not_found（cn/en）。

5. 描述契约

• tools/locales/descs/en|cn/checkpoint.md：增补"告知 Leader"段（打快照后必须报名字；leader 可用 list_checkpoints 核对）。
• tools/locales/descs/en|cn/spawn_teammate.md：fork 机制段补"fork 前先 list_checkpoints 拿权威名字"。

修改文件

新增文件

修改文件

使用示例

# 1. 成员打快照（描述 + 自动通知 leader）
counter-1:  checkpoint(name="count-1", description="报数1完成")
            → 系统自动发 leader: [checkpoint] 'count-1' created by counter-1 at message 2 ...

# 2. Leader fork 前核对名字
Leader:     list_checkpoints
            → name=count-1 message_count=2 created_by=counter-1 description="报数1完成"

# 3. 用确切名字 fork
Leader:     spawn_teammate(name="counter-2", fork="count-1", fork_source="counter-1", ...)

# 万一 fork 名字打错
Leader:     spawn_teammate(name="counter-2", fork="count-2", ...)
            → 系统发 leader: [fork 警告] checkpoint 'count-2' 不存在，可用：count-1
            → leader 立即知道自己用错名字，改用 count-1 重新 fork

验证

Self-checklist:（请自检，在[ ]内打上x，我们将检视你的完成情况，否则会导致pr无法合入）

• • 设计：PR对应的方案是否已经经过Maintainer评审，方案检视意见是否均已答复并完成方案修改
• • 测试：PR中的代码是否已有UT/ST测试用例进行充分的覆盖，新增测试用例是否随本PR一并上库或已经上库
• • 验证：PR描述信息中是否已包含对该PR对应的Feature、Refactor、Bugfix的预期目标达成情况的详细验证结果描述
• • 接口：是否涉及对外接口变更，相应变更已得到接口评审组织的通过，API对应的注释信息已经刷新正确
• • 文档：是否涉及官网文档修改，如果涉及请及时提交资料到Doc仓